<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Module exec</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
</head>
<body bgcolor="white">
<div class="navbar"><a name="#navbar_top"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<hr>

<h1>Module exec</h1>
<ul class="index"><li><a href="#description">Description</a></li><li><a href="#types">Data Types</a></li><li><a href="#index">Function Index</a></li><li><a href="#functions">Function Details</a></li></ul>OS shell command starter.

<p><b>Version:</b> $Revision$
  </p>
<p><b>Behaviours:</b> <a href="gen_server.html"><tt>gen_server</tt></a>.</p>
<p><b>Authors:</b> Serge Aleynikov (<a href="mailto:saleyn@gmail.com"><tt>saleyn@gmail.com</tt></a>).</p>

<h2><a name="description">Description</a></h2>OS shell command starter.
        It communicates with a C++ port process <code>exec-port</code> responsible
        for starting, killing, listing, terminating, and notifying of
        state changes.  The port program serves as a middle-man between
        the OS and the virtual machine to carry out OS-specific low-level
        process control.  The Erlang/C++ protocol is described in the
        <code>exec.cpp</code> file.  The <code>exec-port</code>
        When <code>exec-port</code> is started with a root suid bit set, it
        requires to be provided with the <code>{user, User}</code> option so that it
        will not run as root.  Before changing the effective <code>User</code>,
        it sets the kernel capabilities so that it's able to start
        processes as other users and adjust process priorities.
        At exit the port program makes its best effort to perform
        clean shutdown of all child OS processes.
        Every started OS process is linked to a spawned light-weight
        Erlang process returned by the run/2, run_link/2 command.
        The application ensures that termination of spawned OsPid
        leads to termination of the associated Erlang Pid, and vice
        versa.
  
<h2><a name="types">Data Types</a></h2>

<h3 class="typedecl"><a name="type-cmd_options">cmd_options()</a></h3>
<p><tt>cmd_options() = [Option]</tt>
<ul class="definitions"><li><tt>Option = {cd, WorkDir::string()} | {env, Env} | {kill, Cmd::string()} | {user, RunAsUser::string()} | {nice, Priority::integer()} | {stdout, Device} | {stderr, Device}</tt></li>
<li><tt>Env = [VarEqVal::string()]</tt></li>
<li><tt>Device = null | stdout | stderr | File | {append, File}</tt></li>
<li><tt>File = string()</tt></li>
</ul></p>
<p>Command-line options:
       <dl>
       <dt>{cd, WorkDir}</dt><dd>Working directory</dd>
       <dt>{env, Env}</dt><dd>List of "VAR=VALUE" environment variables</dd>
       <dt>{kill, Cmd}</dt>
           <dd>This command will be used for killing the process. After
               a 5-sec timeout if the process is still alive, it'll be
               killed with SIGTERM followed by SIGKILL.  By default
               SIGTERM/SIGKILL combination is used for process
               termination.</dd>
       <dt>{user, RunAsUser}</dt>
           <dd>When exec-port has a suid bit set, it's capable of running
               commands with a different RunAsUser effective user.</dd>
       <dt>{nice, Priority}</dt>
           <dd>Set process priority between -20 and 20. Note that
               negative values can be specified only when <code>exec-port</code>
               is started with a root suid bit set.</dd>
       <dt>{stdout, Device}</dt>
           <dd>Option for redirecting process's standard output stream</dd>
       <dt>{stderr, Device}</dt>
           <dd>Option for redirecting process's standard error stream</dd>
       </dl></p>

<h3 class="typedecl"><a name="type-exec_options">exec_options()</a></h3>
<p><tt>exec_options() = [Option]</tt>
<ul class="definitions"><li><tt>Option = debug | verbose | {args, Args} | {alarm, Secs} | {user, User} | {limit_users, Users} | {portexe, Exe::string()}</tt></li>
<li><tt>Users = [User]</tt></li>
<li><tt>User = string()</tt></li>
</ul></p>
<p>Options passed to the exec process at startup.
       <dl>
       <dt>debug</dt><dd>Enable port-programs debug trace.</dd>
       <dt>verbose</dt><dd>Enable verbose prints of the Erlang process.</dd>
       <dt>{args, Args}</dt><dd>Append <code>Args</code> to the port command.</dd>
       <dt>{alarm, Secs}</dt>
           <dd>Give <code>Secs</code> deadline for the port program to clean up
               child pids before exiting</dd>
       <dt>{user, User}</dt>
           <dd>When port program is owned by root, this option must be
               specified so that the port program is not running under
               root account.</dd>
       <dt>{limit_users, LimitUsers}</dt>
           <dd>Limit execution of external commands to these set of users.
               This option is only valid when the port program is owned
               by root.</dd>
       <dt>{portexe, Exe}</dt>
           <dd>Provide an alternative location of the port program.
               This option is useful when this application is stored
               on NFS and the port program needs to be copied locally
               so that root suid bit can be set.</dd>
       </dl>.</p>

<h2><a name="index">Function Index</a></h2>
<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#default-0">default/0</a></td><td>Provide default value of a given option.</td></tr>
<tr><td valign="top"><a href="#default-1">default/1</a></td><td></td></tr>
<tr><td valign="top"><a href="#kill-2">kill/2</a></td><td>Send a <code>Signal</code> to a child <code>Pid</code> or <code>OsPid</code>.</td></tr>
<tr><td valign="top"><a href="#ospid-1">ospid/1</a></td><td>Terminate a managed <code>Pid</code> or <code>OsPid</code> process.</td></tr>
<tr><td valign="top"><a href="#run-2">run/2</a></td><td>Start an external program.</td></tr>
<tr><td valign="top"><a href="#run_link-2">run_link/2</a></td><td>Start an external program and link to the OsPid.</td></tr>
<tr><td valign="top"><a href="#start-1">start/1</a></td><td>Start of an external program manager without supervision.</td></tr>
<tr><td valign="top"><a href="#start_link-1">start_link/1</a></td><td>Supervised start an external program manager.</td></tr>
<tr><td valign="top"><a href="#status-1">status/1</a></td><td>Decode the program's exit_status.</td></tr>
<tr><td valign="top"><a href="#stop-1">stop/1</a></td><td>Terminate a managed <code>Pid</code> or <code>OsPid</code> process.</td></tr>
<tr><td valign="top"><a href="#which_children-0">which_children/0</a></td><td>Get a list of children managed by port program.</td></tr>
</table>

<h2><a name="functions">Function Details</a></h2>

<h3 class="function"><a name="default-0">default/0</a></h3>
<div class="spec">
<p><tt>default() -&gt; Default::<a href="#type-exec_options">exec_options()</a></tt></p>
</div><p>Provide default value of a given option.</p>

<h3 class="function"><a name="default-1">default/1</a></h3>
<div class="spec">
<p><tt>default() -&gt; term()</tt></p>
</div>

<h3 class="function"><a name="kill-2">kill/2</a></h3>
<div class="spec">
<p><tt>kill(Pid, Signal::integer()) -&gt; ok | {error, Reason}</tt>
<ul class="definitions"><li><tt>Pid = pid() | OsPid</tt></li>
<li><tt>OsPid = integer()</tt></li>
</ul></p>
</div><p>Send a <code>Signal</code> to a child <code>Pid</code> or <code>OsPid</code>.</p>

<h3 class="function"><a name="ospid-1">ospid/1</a></h3>
<div class="spec">
<p><tt>ospid(Pid::pid()) -&gt; ok | {error, Reason}</tt>
<ul class="definitions"><li><tt>Pid = pid() | OsPid</tt></li>
<li><tt>OsPid = integer()</tt></li>
</ul></p>
</div><p>Terminate a managed <code>Pid</code> or <code>OsPid</code> process.</p>

<h3 class="function"><a name="run-2">run/2</a></h3>
<div class="spec">
<p><tt>run(Exe::string(), Options::<a href="#type-cmd_options">cmd_options()</a>) -&gt; Result</tt>
<ul class="definitions"><li><tt>Result = {ok, Pid::pid(), OsPid::integer()} | {error, Reason}</tt></li>
</ul></p>
</div><p>Start an external program.</p>

<h3 class="function"><a name="run_link-2">run_link/2</a></h3>
<div class="spec">
<p><tt>run_link() -&gt; term()</tt></p>
</div><p>Equivalent to <tt>run / 2</tt>.</p>
<p>Start an external program and link to the OsPid. If OsPid exits,
       the calling process will be killed or if it's trapping exits,
       it'll get {'EXIT', OsPid, Status} message.  If the calling process
       dies the OsPid will be killed.</p>

<h3 class="function"><a name="start-1">start/1</a></h3>
<div class="spec">
<p><tt>start() -&gt; term()</tt></p>
</div><p>Equivalent to <tt>start_link / 1</tt>.</p>
<p>Start of an external program manager without supervision.</p>

<h3 class="function"><a name="start_link-1">start_link/1</a></h3>
<div class="spec">
<p><tt>start_link(Options::<a href="#type-options">options()</a>) -&gt; {ok, Pid::pid()} | {error, Reason}</tt></p>
</div><p>Supervised start an external program manager.</p>

<h3 class="function"><a name="status-1">status/1</a></h3>
<div class="spec">
<p><tt>status(Status::integer()) -&gt; {status, ExitStatus::integer()} | {signal, Signal::integer(), Core::<a href="#type-boolean">boolean()</a>}</tt></p>
</div><p>Decode the program's exit_status.</p>

<h3 class="function"><a name="stop-1">stop/1</a></h3>
<div class="spec">
<p><tt>stop(Pid) -&gt; ok | {error, Reason}</tt>
<ul class="definitions"><li><tt>Pid = pid() | OsPid</tt></li>
<li><tt>OsPid = integer()</tt></li>
</ul></p>
</div><p>Terminate a managed <code>Pid</code> or <code>OsPid</code> process.</p>

<h3 class="function"><a name="which_children-0">which_children/0</a></h3>
<div class="spec">
<p><tt>which_children() -&gt; [OsPid::integer()]</tt></p>
</div><p>Get a list of children managed by port program.</p>
<hr>

<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<p><i>Generated by EDoc, Aug 20 2008, 12:40:47.</i></p>
</body>
</html>
